SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/CGI::Push.Z/CGI::Push

Text File | 1998-10-28 | 10.4 KB | 331 lines

     CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))



     NNNNAAAAMMMMEEEE
      CGI::Push - Simple Interface to Server Push

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          use CGI::Push qw(:standard);

          do_push(-next_page=>\&next_page,
              -last_page=>\&last_page,
              -delay=>0.5);

          sub next_page {
          my($q,$counter) = @_;
          return undef if $counter >= 10;
          return start_html('Test'),
             h1('Visible'),"\n",
             "This page has    been called ", strong($counter)," times",
             end_html();
        }

           sub last_page {
           my($q,$counter) = @_;
           return start_html('Done'),
              h1('Finished'),
              strong($counter),' iterations.',
              end_html;
           }


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      CGI::Push is a subclass of the CGI object created by CGI.pm.
      It is    specialized for    server push operations,    which allow
      you to create    animated pages whose content changes at
      regular intervals.

      You provide CGI::Push    with a pointer to a subroutine that
      will draw one    page.  Every time your subroutine is called,
      it generates a new page.  The    contents of the    page will be
      transmitted to the browser in    such a way that    it will
      replace what was there beforehand.  The technique will work
      with HTML pages as well as with graphics files, allowing you
      to create animated GIFs.

     UUUUSSSSIIIINNNNGGGG CCCCGGGGIIII::::::::PPPPuuuusssshhhh
      CGI::Push adds one new method    to the standard    CGI suite,
      _d_o__p_u_s_h().  When you call this method, you pass it a
      reference to a subroutine that is responsible    for drawing
      each new page, an interval delay, and    an optional subroutine
      for drawing the last page.  Other optional parameters
      include most of those    recognized by the CGI _h_e_a_d_e_r() method.

      You may call _d_o__p_u_s_h() in the    object oriented    manner or not,
      as you prefer:



     Page 1                        (printed 10/23/98)






     CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))



          use CGI::Push;
          $q = new CGI::Push;
          $q->do_push(-next_page=>\&draw_a_page);

          -or-

          use CGI::Push qw(:standard);
          do_push(-next_page=>\&draw_a_page);

      Parameters are as follows:

      -next_page

          do_push(-next_page=>\&my_draw_routine);

          This required parameter points to    a reference to a
          subroutine responsible for drawing each new page.     The
          subroutine should    expect two parameters consisting of
          the CGI object and a counter indicating the number of
          times the    subroutine has been called.  It    should return
          the contents of the page as an aaaarrrrrrrraaaayyyy of one or more
          items to print. It can return a false value (or an empty
          array) in    order to abort the redrawing loop and print
          out the final page (if any)

          sub my_draw_routine {
              my($q,$counter) =    @_;
              return undef if $counter > 100;
              return start_html('testing'),
                 h1('testing'),
                 "This page    called $counter    times";
          }

          You are of course    free to    refer to create    and use    global
          variables    within your draw routine in order to achieve
          special effects.

      -last_page
          This optional parameter points to    a reference to the
          subroutine responsible for drawing the last page of the
          series.  It is called after the -next_page routine
          returns a    false value.  The subroutine itself should
          have exactly the same calling conventions    as the
          -next_page routine.

      -type
          This optional parameter indicates    the content type of
          each page.  It defaults to "text/html".  Normally    the
          module assumes that each page is of a homogenous MIME
          type.  However if    you provide either of the magic    values
          "heterogeneous" or "dynamic" (the    latter provided    for
          the convenience of those who hate    long parameter names),



     Page 2                        (printed 10/23/98)






     CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))



          you can specify the MIME type -- and other header    fields
          -- on a per-page basis.  See "heterogeneous pages" for
          more details.

      -delay
          This indicates the delay,    in seconds, between frames.
          Smaller delays refresh the page faster.  Fractional
          values are allowed.

          IIIIffff nnnnooootttt ssssppppeeeecccciiiiffffiiiieeeedddd,,,,    ----ddddeeeellllaaaayyyy wwwwiiiillllllll ddddeeeeffffaaaauuuulllltttt ttttoooo 1111 sssseeeeccccoooonnnndddd

      -cookie, -target, -expires
          These have the same meaning as the like-named parameters
          in _C_G_I::_h_e_a_d_e_r().

      HHHHeeeetttteeeerrrrooooggggeeeennnneeeeoooouuuussss    PPPPaaaaggggeeeessss

      Ordinarily all pages displayed by CGI::Push share a common
      MIME type.  However by providing a value of "heterogeneous"
      or "dynamic" in the _d_o__p_u_s_h()    -type parameter, you can
      specify the MIME type    of each    page on    a case-by-case basis.

      If you use this option, you will be responsible for
      producing the    HTTP header for    each page.  Simply modify your
      draw routine to look like this:

          sub my_draw_routine {
          my($q,$counter) = @_;
          return header('text/html'),    # note we're producing the header here
             start_html('testing'),
             h1('testing'),
             "This page called $counter times";
          }

      You can add any header fields    that you like, but some
      (cookies and status fields included) may not be interpreted
      by the browser.  One interesting effect is to    display    a
      series of pages, then, after the last    page, to redirect the
      browser to a new URL.     Because _r_e_d_i_r_e_c_t() does b<not>    work,
      the easiest way is with a -refresh header field, as shown
      below:














     Page 3                        (printed 10/23/98)






     CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))



          sub my_draw_routine {
          my($q,$counter) = @_;
          return undef if $counter > 10;
          return header('text/html'),    # note we're producing the header here
             start_html('testing'),
             h1('testing'),
             "This page called $counter times";
          }

          sub my_last_page {
          header(-refresh=>'5; URL=http://somewhere.else/finished.html',
             -type=>'text/html'),
          start_html('Moved'),
          h1('This is the last page'),
          'Goodbye!'
           hr,
           end_html;
          }


      CCCChhhhaaaannnnggggiiiinnnngggg tttthhhheeee PPPPaaaaggggeeee DDDDeeeellllaaaayyyy oooonnnn tttthhhheeee FFFFllllyyyy

      If you would like to control the delay between pages on a
      page-by-page basis, call _p_u_s_h__d_e_l_a_y()    from within your draw
      routine.  _p_u_s_h__d_e_l_a_y() takes a single    numeric    argument
      representing the number of seconds you wish to delay after
      the current page is displayed    and before displaying the next
      one.    The delay may be fractional.  Without parameters,
      _p_u_s_h__d_e_l_a_y() just returns the    current    delay.

     IIIINNNNSSSSTTTTAAAALLLLLLLLIIIINNNNGGGG    CCCCGGGGIIII::::::::PPPPuuuusssshhhh SSSSCCCCRRRRIIIIPPPPTTTTSSSS
      Server push scripts mmmmuuuusssstttt be installed    as no-parsed-header
      (NPH)    scripts    in order to work correctly.  On    Unix systems,
      this is most often accomplished by prefixing the script's
      name with "nph-". Recognition    of NPH scripts happens
      automatically    with WebSTAR and Microsoft IIS.     Users of
      other    servers    should see their documentation for help.

     CCCCAAAAVVVVEEEEAAAATTTTSSSS
      This is a new    module.     It hasn't been    extensively tested.

     AAAAUUUUTTTTHHHHOOOORRRR IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN
      be used and modified freely, but I do    request    that this
      copyright notice remain attached to the file.     You may
      modify this module as    you wish, but if you redistribute a
      modified version, please attach a note listing the
      modifications    you have made.

      Address bug reports and comments to:
      [e-mail]

     BBBBUUUUGGGGSSSS



     PPPPaaaaggggeeee 4444                        ((((pppprrrriiiinnnntttteeeedddd 11110000////22223333////99998888))))






     CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))    22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      CCCCGGGGIIII::::::::PPPPuuuusssshhhh((((3333))))



      This section intentionally left blank.

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
      the _C_G_I::_C_a_r_p    manpage, the _C_G_I manpage



















































     Page 5                        (printed 10/23/98)